The ToDo List application is fully scriptable – anything that you can do to a document using the keyboard and mouse, can be done by a script using the AppleEvents supported by ToDo List. Using AppleScript (which is available for free on every Macintosh), you can create powerful custom solutions that combine the features of ToDo List with other scriptable applications. For example, you might already be using ToDo List as a convenient place to keep a list of files you plan to download from Info-Mac. With a simple script, you could automatically iterate through all of the items in the list and for each, use Anarchie (which is also scriptable) to download the file to your machine.
This chapter provides an overview of the elements in ToDo List that you can control, and the commands that are available to control them. It assumes that you already have some familiarity with AppleScript.
The ToDo List Elements
Scriptable applications are typically made up of a variety of elements that can be specified (the 5th item of the document "Stuff") and a set of actions that can be performed on those elements. ToDo List provides a hierarchy of element types and a variety of ways to refer to them.
At the top of the hierarchy is a single application. The application has a number of properties (that correspond to the current preferences) that can be addressed directly:
autoOpen boolean -- should ToDo List automatically open your last documents when launched
confirmDelete boolean -- confirm deletes
play toggle sound boolean -- play sound when toggling items
saveOnClose boolean -- automatically save documents on close
saveInterval integer -- save documents after this number of minutes (0 = don't auto-save)
returnKeyClicksOK boolean -- <return> same as hitting OK in item dialog
You can retrieve or change any of these properties using AppleScript:
set areWeAutoOpening to the autoOpen of application "ToDo List"
set the autoOpen of application "ToDo List" to true
The application also contains some number of document elements (one for each ToDo List document). You can refer to the documents by name or by index:
document "Things To Do" of application "ToDo List"
document 3 of application "ToDo List"
Each document has several properties that can be addressed directly:
name string -- the title of the document
show calendar boolean -- should the calendar be shown across the top of the document
use dates boolean -- should all items have a due date associated with them
show overdue boolean -- show how many days each item is overdue
carryforward unfinished boolean -- should unfinished items be carried forward
date font string -- font to use for displaying dates
date size integer -- size of font for displaying dates
item font string -- font for displaying items
item size integer -- font size for displaying items
clipboard text only boolean -- should copying to the clipboard copy only text
voice string -- voice that should be used for speaking items
useSmallCalendarFont boolean -- if true, then a very small font is used for calendar
You can change these properties using AppleScript:
tell application "ToDo List"
set the date font of document "Important Stuff" to "Times"
set the show overdue of document 4 to false
end tell
Documents also contain some number of item elements. These elements can be accessed by index:
item 5 of document 4
If the list is using due dates, then items can also be accessed via the date:
item 3 of date "1/13/96" of document 4
item 6 of date "June 1, 1996" of document "Stuff"
Each item has a number of properties that you can retrieve or set:
uniqueID integer [r/o] -- a unique ID for the to do item
description string -- the text of the to do item
dueDate string -- the date the item should be done on
completed boolean -- has the item been completed (true or false)
created string [r/o] -- date and time that the item was created
priority integer -- priority of the item (0 - 10, 0 = none, 1 = highest)
modified string [r/o] -- date and time that the item was last modified
selected boolean -- true if the item is currently selected
You can access these properties from AppleScript by just fully specifying the item and property. For example:
tell application "ToDo List"
-- Check off an item as finished
set the completed of item 4 of document "Important Stuff" to true
-- Change the due date of an item
set the dueDate of item 2 of date "5/16/96" of
document 3 to "May 20, 1996"
end tell
You can create new elements using the make command.
AppleScript Commands
ToDo List supports the standard open, print, and quit AppleEvents, so you can easily get it to launch and open a set of ToDo List documents. It also lets you save and close documents as needed:
save: save the document to disk
save document
[in alias] -- file to save the document in
close: close the document's window
close document -- document to close
[saving yes/no/ask] -- should any changes be saved
[saving in alias] -- file to save the document in
For example:
tell application "ToDo List"
open alias "My Harddisk:Lists:Stuff To Do"
set the voice of document "Stuff To Do" to "Victoria"
save document "Stuff To Do"
close document "Stuff To Do"
end tell
ToDo List also supports several core AppleEvents that let you count, create, delete, etc. the various elements that it defines:
count: count the number of elements in a class
count reference -- the object whose elements are to be counted
each type class -- the class of the elements to be counted.
Result: integer -- the number of elements in the given class
For example:
tell application "ToDo List"
set cnt to count of documents
set numItems to count of item of document 3
set dayItems to count each item of date "5/6/96" of document "Stuff"
set numDates to count each date of document 1
end tell
get: get data for a to do item
get reference -- reference to the item to get
Result: anything -- data for the requested to do item
set: set an item or property of an item to some value
set reference -- the item or item property to change
to anything -- new value for the item or property
make: make a new item
make
new type class
[at integer]
with properties record
within reference -- the document to which the new item should be added
Result: integer -- index of the new item
Makes a new item of the given type ("item" or "document"). Any unspecified properties default to the same values as they would if the item were created directly in ToDo List. For example:
tell application "ToDo List"
-- Note: make new document doesn't support 'with properties'!
set docNum to make new document
set docName to get name of document docNum
set the use dates of document docName to true
make new item at 1 within document docName
with properties { description:"testing", priority: 1,
dueDate:"Feb 1, 1996"}
make new item at 9999 within document docName
with properties { description:"testing", priority: 0,
completed: true, dueDate:"Feb 1, 1996"}
end tell
delete: delete an item from the document
delete reference -- the item to delete
For example:
tell application "ToDo List"
delete item 1 of document "Stuff"
delete item 1 of date "5/5/96" of document 2
end tell
move: move the referenced item to a new location, changing its due date and priority if necessary
move reference -- a reference to the item to be moved
to integer -- index of the location the item should be moved to
Moves an item from one location to anotherwithin the same document. If necessary, the priority or due date of the item will be modified to match the new location. For example:
tell application "ToDo List"
-- Move the first item to the end of the list
move item 1 of document "Stuff" to 9999
-- Swap the first and second items
move item 1 of document "Stuff" to 2
end tell
ToDo List also supports several custom AppleEvents that let you control the special features of the application:
SpeakItems: Read all of the unfinished items in the list
SpeakItems document -- the ToDo List document to speak items from
SpeakTodaysItems: Read all of the unfinished items for today
SpeakTodaysItems document -- the ToDo List document to read today's items from
synchronizeNewton: synchronize the given document with a Newton
synchronizeNewton document -- the ToDo List document to synchronize to
[via serial-modem/serial-printer/modem/AppleTalk]
-- synchronize Newton using this connection (serial, AppleTalk, modem)
[using string] -- option string for the connection
export: export the selected items (or all if none are selected) in the given ToDo List document to a tab-delimited text file.
export document -- the ToDo List document to export to a text file
[as text/HTML] -- type of document to create (text or HTML).
[in alias] -- the file to export the ToDo List document into
import: import items from a tab-delimited text file
import document -- the ToDo List document to import the items into
[from alias] -- the tab-delimited text file to import the items from
